home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / answers / comp / ph-faq < prev    next >
Internet Message Format  |  1994-04-05  |  21KB

  1. Path: bloom-beacon.mit.edu!hookup!europa.eng.gtefsd.com!gatech!concert!news.wfu.edu!news
  2. From: ph-faq@wfu.edu
  3. Newsgroups: info.ph,comp.infosystems.gopher,comp.infosystems.www,comp.answers,news.answers
  4. Subject: ph (cso nameserver) Frequently Asked Questions (FAQ)
  5. Followup-To: comp.infosystems.www
  6. Date: 5 Apr 1994 10:59:11 GMT
  7. Organization: Wake Forest University
  8. Lines: 523
  9. Approved: news-answers-request@MIT.Edu
  10. Message-ID: <2nrg9v$gfl@quad.wfunet.wfu.edu>
  11. NNTP-Posting-Host: ac.wfunet.wfu.edu
  12. Xref: bloom-beacon.mit.edu info.ph:404 comp.infosystems.gopher:11023 comp.infosystems.www:12528 comp.answers:4779 news.answers:17704
  13.  
  14. Archive-name: ph-faq
  15.  
  16. FAQ (Frequently-asked Questions) for ph (cso nameserver) 
  17. ============================================================================
  18.  
  19. Last modified Mar. 2, 1994
  20.  
  21. The FAQ is maintained by Noel Hunter <noel@wfu.edu>.  Please send comments / 
  22. corrections to ph-faq@wfu.edu.
  23.  
  24. This FAQ is automatically posted on the 5th and 20th of each month. The
  25. latest version of the FAQ is available in the following ways: 
  26.  
  27. anonymous ftp and fsp to ftp.wfu.edu /pub/usenet/ph-FAQ
  28. gopher to gopher.wfu.edu port 70 /Wake Forest Information/Computer information
  29.                                  /Usenet News information maintained by Wake...
  30.  
  31. This FAQ is also mailed to the list info-ph@uxc.cso.uiuc.edu. To get on
  32. the ph mailing list, send mail to majordomo@listserv.cso.uiuc.edu with
  33. "subscribe info-ph" in the BODY (not Subject: !)
  34.  
  35. ============================================================================
  36. Acknowledgements
  37. ============================================================================
  38. Many of these answers came from the info-ph list.  Some are paraphrased,
  39. edited, or otherwise altered, and some are not credited.  But my thanks
  40. goes out to all who have contibuted to the list.  And if you see something
  41. of yours here which you want credited, let me know, and I will credit it.
  42.  
  43. Thanks to Sandra Louie for her list of several FAQs.
  44.  
  45. ============================================================================
  46. Submissions
  47. ============================================================================
  48.  
  49. The maintainer is not an expert on ph/cso.  I am relying on experts to 
  50. submit FAQs and answers.  I am also relying on users of the FAQ to let me 
  51. know which answers are unclear, and where there are errors or omissions.
  52. At present, this is just a start.  You can help make it more complete.
  53.  
  54. To submit, send email to: ph-faq@wfu.edu.  If you do NOT want your name
  55. credited in the FAQ, please say so.
  56.  
  57. ============================================================================
  58. Contents
  59. ===========================================================================
  60.  
  61. Section 0: What is CSO/qi/ph?
  62.  
  63. Section 1: Setting up and installing a server
  64.         1.1 Where do I get the ph / cso software?
  65.         1.2 How do I install the ph / cso software
  66.     1.3 How do I create a ph database?
  67.     1.4 How do I enable phquery for fuzzy mail addressing?
  68.     1.5 Can I run multiple databases on different ports?
  69.     1.5 How can I register my server?
  70.  
  71. Section 2: Common problems / error messages
  72.     2.1 How do I fix "Oops, lost connection to server"
  73.     2.2 How do I do searches using strings with blanks in them?
  74.     2.3 How do I limit the number of responses?
  75.     2.4 Ph is working fine for some entries, but returns "No matches to
  76.         your query" for other entries (especially new entries) 
  77.  
  78. Section 3: Questions that have not been answered
  79.     3.1 How can you get a qi server to not only compile but actually
  80.     serve queries off of a Solaris 2.X machine?
  81.  
  82. Section 4: Other questions
  83.     4.1 What does CSO stand for?
  84.  
  85. ===========================================================================
  86. Section 0: What is CSO/qi/ph?
  87. ===========================================================================
  88.  
  89. The CSO nameserver provides an efficient database for the storage and
  90. retrieval of a variety of information over the Internet.  Its primary
  91. use is for telephone and email directories, but it may be used to
  92. store any type of information.
  93.  
  94. The CSO server software is called "qi".  It runs on a variety of platforms,
  95. primarily mainframe or minicomputer-type machines with Internet connections.
  96.  
  97. The CSO client software is called "ph".  It runs on virtually every major
  98. platform in use on the Internet, from Unix to Mac and PC.  Client functions
  99. are also built into many of the programs used to provide friendly interfaces
  100. to the Internet, such as gopher, World-Wide Web, and their associated 
  101. clients (lynx, mosaic, etc.).
  102.  
  103. ===========================================================================
  104. Section 1: Setting up and installing a server
  105. ===========================================================================
  106.  
  107. Subject: 1.1 Where do I get the ph / cso software?
  108.  
  109. The software is available via anonymous ftp from:
  110.  
  111. Currently: vixen.cso.uiuc.edu, in the pub subdirectory.  However, the uiuc
  112. staff has announced that in the near future, the address will be 
  113. ftp.cso.uiuc.edu.
  114.  
  115. - qi.tar.gz (server) lives on vixen.cso.uiuc.edu, pub subdirectory.
  116. - ph.tar.gz (clients) lives on vixen.cso.uiuc.edu, pub subdirectory.
  117.  
  118. Current versions:
  119. qi: 2.2
  120. ph: 6.5
  121.  
  122. ===========================================================================
  123. Subject: 1.2 How do I install the ph / cso software?
  124.  
  125. Server
  126. ------
  127. To install the server without reading any instructions, look in the configs
  128. directory (in qi).  Change the file "defaults" to include your domain
  129. name, desired directories, and features.  Then look for a config file for
  130. your system.  Finally, in the main qi dir, type:
  131.  
  132. Configure systemtype
  133. make install
  134.  
  135. Finally, build the database (see 1.3, below), and modify your inetd.conf
  136. file and your services files to reference the server.  Here are sample
  137. entries:
  138.         
  139. In services:
  140. ns                  105/tcp
  141.  
  142. If you are using NIS, run ypmake after modifying services.
  143. In inetd.conf:
  144. ns                  stream tcp nowait root   /usr/local/lib/cso/qi qi -d -t30
  145.          
  146. After modifying inetd.conf, make the inetd reload inetd.conf:
  147.  
  148. inetd -c
  149.  
  150. Client
  151. ------
  152. Unix: The Unix client comes as part of the server package.  The easiest way
  153. to install it is to do it as part of the server package, above.  The 
  154. Configure script will automatically generate a Makefile for your system, and
  155. will make and install the ph client.  If for some reason you cannot make
  156. the entire qi package, here are the minimal steps for making the client:
  157.  
  158. Look in the configs directory (in qi).  Change the file "defaults" to
  159. include your domain name, desired directories, and features.  Then look
  160. for a config file for your system.  Finally, in the main qi dir, type: 
  161.  
  162. Configure systemtype
  163.  
  164. Next, make the api library used by ph:
  165. cd api
  166. make
  167.  
  168. Finally, bo back to the qi dir, cd to the ph dir, and do a make:
  169.  
  170. cd ..
  171. cd ph
  172. make
  173.  
  174. If all goes well, finish with:
  175. make install
  176.  
  177. Note that the client distribution (a separate from the entire qi 
  178. distribution), includes a Makefile already generated for a system at uiuc.
  179. While it is possible to edit this Makefile (despite the "Do not edit" 
  180. warning at the top of the file), it is much easier to make ph as a part 
  181. of qi.
  182.  
  183. Other clients:
  184. The ph distribution comes with clients for the following systems:
  185.  
  186. a. CMS, requires TCP/IP for VM Version 1.2 or later IBM C/370 Compiler and
  187.    Runtime library (Version 1.2.0)
  188. b. DOS, with both source and executable, requires MS-DOS, PC/TCP by FTP 
  189.    Software
  190. c. MAC, requires MacTCP
  191. d. Next
  192. e. PC-NFS version (for MS-DOS and SUN's PC-NFS)
  193. f. VM, in Pascal
  194. g. VMS 5.3 with Wollongong WIN/TCP 5.1
  195. h. Windows (with winsock)
  196. i. X-Windows
  197.  
  198. Some other clients not part of the distribution:
  199.  
  200. Most gopher browsers support PH queries
  201. Many World-Wide-Web browsers
  202. Some Mail packages (notably Eudora)
  203.  
  204. Other Vax/VMS clients available via anoynmous ftp:
  205.   UCX:           esa.lanl.gov
  206.   UCX:           noc.macc.wisc.edu
  207.   Multinet:      icaen.llnl.gov
  208.   UCX & Mulinet: ftp.ceri.memst.edu
  209.  
  210. ===========================================================================
  211. Subject: 1.3 How do I create a ph database?
  212.  
  213. To create a database, you need to define the fields for the database,
  214. determine its size, create a text file of data to be input into the
  215. database, then run the database building programs.
  216.  
  217.     a. Defining the database
  218.     A ph database is defined by a "cnf" file.  The default file which
  219.     comes with ph is "prod.cnf".  It's a good idea to start with a copy
  220.     of this file, and to change as little as possible.  Some clients
  221.     rely on the names of certain fields in the cnf file, so changing 
  222.     them can cause unforseen problems.  The ph installation instructions
  223.     specifically state that you should NOT change the following fields:
  224.  
  225.     Used in ph source code
  226.     ----------------------
  227.     2:email
  228.     3:name
  229.     4:type
  230.     5:id
  231.     6:alias
  232.     7:password
  233.     8:proxy
  234.     23:nickname
  235.     25:all
  236.     30:hero
  237.     43:suppress
  238.  
  239.     Used by utilities and clients
  240.     -----------------------------
  241.         0:address
  242.         1:phone
  243.         9:department
  244.         10:title
  245.         11:curriculum
  246.         20:home_address
  247.         21:permanent_address
  248.         22:office_address
  249.         26:callsign
  250.         31:no_update
  251.         32:office_phone
  252.         33:home_phone
  253.         35:high_school
  254.         37:permanent_phone
  255.         42:left_uiuc
  256.  
  257.     You should be able to change other fields without causing too many 
  258.     problems.  For each field in the file, you will see a field number, 
  259.     a field name, the number of bytes in the field, a descriptive name, and
  260.     a list of properties for the field.  Each of these items is separated
  261.     by a colon, with field entries separated by new lines.  You will
  262.     probably want to change the descriptions of some of the fields, as
  263.     well as their length in bytes, but you should generally leave the names
  264.     and numbers alone.
  265.  
  266.     There are numerous properties you can assign to a field, and most sites
  267.     will want to customize these properties.  The most commonly changed
  268.     properties are as follows:
  269.     
  270.         1. Lookup: if present, clients can search on this field
  271.         2. Public: if present, clients can see this field.  LocalPub
  272.            is a variation which allows only clients in the local 
  273.            domain to see the field.  If neither is present, only
  274.            the system administrators and owners can see the field.
  275.         3. Default: If this is present, the contents of the field
  276.            are returned on normal searches.  If not present, the
  277.            contents are returned only when specifically requested
  278.            by the client.
  279.         4. Change: if present, clients who have authenticated (logged
  280.            in) can change the contents of the field.
  281.  
  282.     b. Creating an input file
  283.     To create an input file, you create a tab-delimited file containing
  284.     the information for the database.  Each line will be composed of
  285.     field numbers, a colon, the data for the field, and a tab (if 
  286.     another field follows).  The format looks like this:
  287.  
  288.     fieldnum:data-for-field (tab)    fieldnum:data-for-field... (new line)
  289.     
  290.     Here's a simple example:
  291.  
  292.     3:Hunter, Noel C    32:759-5812     22:POBox 7408    4:p
  293.     3:Dominick, James Lyon    32:759-5261    4:p
  294.  
  295.     This example has two records, one for Noel Hunter, and one for James
  296.     Dominick.  Both records include data for fields 3,4 and 32, and the 
  297.     entry for Noel Hunter also has data for field 22.  
  298.  
  299.     Notice that the entries do not have to be in any order, and that some
  300.     entries can contain more fields than others.  Field 4, the "type"
  301.     field, must be present if you want ph to limit the number of entries
  302.     returned by searches.
  303.  
  304.     c. Building the database
  305.     Assuming that the database cnf file (see a, above) is called
  306.     "prod.cnf", and the database text input file (see b, above)
  307.     is called "qi.input", we can create a ph database with the 
  308.     following commands:
  309.  
  310.     #!/bin/sh
  311.         # PH database build script
  312.     # Designed from numerous contributions to the info-ph list
  313.     #
  314.     # cd to the cso library directory.  We assume all the cso programs
  315.     # are installed here:
  316.     cd /usr/local/lib/cso
  317.     #
  318.         # Remove the old database files if the exist:
  319.     rm -f prod.bdx prod.dir prod.dov prod.idx prod.iov prod.lck prod.seq
  320.     #
  321.     # Determine the size for the database using the "sizedb" program
  322.     # that comes with the server.  You need perl to use sizedb, along
  323.     # with the file primes.shar.  If you don't have these, you can hard-
  324.     # code in a prime bigger than the number of indexed fields (from the
  325.     # cnf file) times the number of records in your database (qi.input):
  326.     size=`./sizedb prod.cnf qi.input`
  327.     #
  328.     # Build the database using the specifications in "prod.cnf", and the
  329.     # data in "qi.input"
  330.     ./credb $size prod
  331.     ./maked prod <qi.input
  332.     ./makei prod
  333.     ./build -s prod
  334.     #
  335.     # Clean up:
  336.     rm prod.sta
  337.     #
  338.     # Set permissions so that users cannot access the database directly.
  339.     # We assume that the qi server is running under a login that can
  340.     # access the files:
  341.     chmod -R o-rwx,g-rwx *
  342.  
  343. ===========================================================================
  344. Subject: 1.4 How do I enable phquery for fuzzy mail addressing?
  345.  
  346. (contributed by Sverre Froyen, modified by Noel Hunter)
  347.  
  348. Fuzzy addressing is done by the program "phquery", part of the ph client
  349. distribution.  Fuzzy addressing allows users to send mail based on a person's
  350. real name, rather than their login ID.  Phquery performs the conversion from
  351. the real name to an email address, using the ph database.  Adding phquery
  352. is complicated, and you must be very careful or you will disrupt incoming 
  353. mail.  If possible, try it out on a non-production system first.
  354.  
  355. To make it work, first compile phquery on your machine.  It's part of the
  356. ph client distribution available from the main ftp archive (see 1.3, below).
  357.  
  358. After compiling it, you want to make sure that it works correctly by running it
  359. in debug mode. Type, e.g.,
  360.  
  361. phquery -d -f your-address test-name < /dev/null
  362.  
  363. If it works, you are ready to install it by changing you sendmail
  364. configuration file to route incoming messages through phquery.  How you do
  365. this will vary with each version of Unix, but here is a sample.
  366.  
  367. On most Unix systems, the file to alter is sendmail.cf.  Here are diffs of
  368. how it was done on one system:
  369.  
  370. Adding the phquery mailer:
  371.  
  372. *** 235,240 ****
  373. --- 239,248 ----
  374.   Mlocal,       P=/bin/mail, F=flsSDFMmnP, S=10, R=20, A=mail -d $u
  375.   Mprog,        P=/bin/sh,   F=lsDFMeuP,  S=10, R=20, A=sh -c $u
  376.   
  377. + # Phquery specification
  378. + MPH,  P=/etc/phquery, F=DFMhnmur, A=phquery $u
  379.   S10
  380.   # None needed.
  381.   
  382. ***************
  383.  
  384. Adding the rule to invoke phquery:
  385.  
  386. *** 353,364 ****
  387. --- 361,376 ----
  388.   # Handle special cases.....
  389.   R@                    $#local $:$n                    handle <> form
  390.   
  391. + # Invoke phquery to resolve names addressed to domain (sverre)
  392. + R$+<@LOCAL>           $#PH $@$w $:$1
  393.   # resolve the local hostname to "LOCAL".
  394.   R$*<$*$=w.LOCAL>$*    $1<$2LOCAL>$4                   thishost.LOCAL
  395.   R$*<$*$=w.uucp>$*     $1<$2LOCAL>$4                   thishost.uucp
  396.   R$*<$*$=w>$*          $1<$2LOCAL>$4                   thishost
  397.   
  398. ***************
  399.  
  400. Note that I had to add the phquery rule before the local hostname gets
  401. resolved to LOCAL.  After this point there is no way to distinguish mail
  402. to the domain from mail to the local host and a mail loop will result.
  403. Also make sure that From: line contains the hostname and not just the
  404. domain name.  Our mailer used just the domainname and I had a wonderful
  405. mail loop bouncing mail with another site because phquery could not
  406. resolve MAILER_DAEMON.  You can check your sendmail.cf file by running
  407. sendmail (by hand) with the -bt option, i.e.,
  408.  
  409. /usr/lib/sendmail -bt -C new-configuration file
  410.  
  411. and asking it to invoke the various rules, type for instance
  412.  
  413. 4,0 some-address
  414.  
  415. and it will show how rules 4 and 0 treats the address.
  416.  
  417. ===========================================================================
  418. Subject: 1.5 Can I run multiple databases on different ports?
  419.  
  420. Yes.  You can use one binary (copy of the software).  On a Unix system, 
  421. make multiple entries in /etc/services and /etc/inetd.conf, and use the
  422. -DATABASE option with each entry in /etc/inetd.conf to specify the desired
  423. database for that port.
  424.  
  425. ===========================================================================
  426. Subject: 1.6 How can I register my CSO server?
  427.  
  428. You can send a note to Joel Cooper (cooper@utopia.cc.nd.edu) or (John
  429. Norstad, j-norstad@nwu.edu) . They need to know the name of your
  430. institution as you wish it to appear in the directory, plus the domain
  431. name of your new CSO server.  Joel maintains the list used by Gopher. They
  432. try to keep their lists synchronized, so you only need to tell one of
  433. them. John had announced that he would soon stop maintaining the list for
  434. the Mac client, but has since been persuaded to continue maintaining the list. 
  435.  
  436. ===========================================================================
  437. Section 2: Common problems / error messages
  438. ===========================================================================
  439.  
  440. Subject: 2.1 How do I fix "Oops, lost connection to server"
  441.  
  442. There are many possible causes for this problem.  Here is a list of
  443. things to check:
  444.  
  445.     1. Are the permissions set so that the login running qi (look in
  446.        your "inetd.conf" file to determine the login) can read all
  447.        of the files?  The permissions should look something like
  448.        this (assuming the user is root):
  449.  
  450.     -rw-------   1 root     sys      3153408 Dec  6 05:03 prod.*
  451.     -rwx------   1 root     sys       180224 Nov 30 11:22 qi
  452.  
  453.        If qi is not running as root, you need to chown the files
  454.        so that the qi user can read them, and can execute qi.
  455.  
  456.     2. Are the ph binaries installed in the right place (specified
  457.        during the make and in "inetd.conf"?  Is the ph directory 
  458.        accessible?  Did you move the sources after you installed (this
  459.        can cause problems).
  460.  
  461.     3. Did you build the database, and did it work (see 1.3)?
  462.  
  463.     4. Are the service names in /etc/services and /etc/inted.conf the
  464.        same, and are they the same as the one specified in the makefiles?
  465.  
  466.     5. Did you restart inetd (with inetd -c), and rebuild the NIS database
  467.        (if using NIS, run ypmake), after you installed ph?
  468.  
  469.     6. Is the prod.cnf (or other cnf) file for your database in the
  470.        same directory as the database (it has to be).
  471.  
  472.     7. If the client does not have a registered domain name, qi may be
  473.        denying access.  Try compiling with the the -DNOCHECKNET option
  474.        (add that to your "$Cflags" variable in the config file used to
  475.         build qi and then rebuild qi.)
  476.  
  477.  
  478.  
  479. ===========================================================================
  480. Subject: 2.2 How do I do searches using strings with blanks in them?
  481.  
  482. (contributed by guthery@austin.slcs.slb.com)
  483.  
  484. Suppose the field you are searching is called Address and you want
  485. all the Smiths who live in "New York".  You would enter the following
  486. in the Ph command box:
  487.  
  488.         name=Smith address=New address=York
  489.  
  490. ===========================================================================
  491. Subject: 2.3 How do I limit the number of responses?
  492.  
  493. To limit the number of responses returned, you need to do two things:
  494.  
  495. 1. When compiling the server, set the "person limit", in the file
  496. qi/configs/defaults.  Look for the line:
  497.  
  498.   "PersonLimit","100",                  # max # of people to return
  499.  
  500. and set the value (100 in this example) to the desired number of entries.
  501.  
  502. 2. For all records you want to limit, you must set the "type" field to
  503. "person", or "p".  When you are building the database, just include data
  504. for the type field (field 4) with each person's entry (see the example
  505. in section 1.3).
  506.  
  507. ===========================================================================
  508. Subject: 2.4 Ph is working fine for some entries, but returns "No matches to 
  509. your query" for other entries (especially new entries)
  510.  
  511. After building a small test database then adding and modifying entries, a
  512. query to the database returns "No matches to your query".  Since the entry
  513. has just been added (and qi acknowledged that it has been added), the user
  514. knows the entry is there.  If the user queries one of the original entries
  515. in the database that has not been modified, that entry will usually be
  516. found. This problem is due to the fact that the original database is small
  517. so the SIZE returned from sizedb is small.  If SIZE is used when building
  518. the database, there is not much room for the database to grow. Use a 
  519. larger value for size to avoid this problem (see Subject 1.3).
  520.  
  521. ===========================================================================
  522. Subject: 4.1 What does CSO stand for?
  523.  
  524. Computing and Communications Services Office (at the University of Illinois).
  525.  
  526. End of ph-FAQ.
  527.  
  528. ===========================================================================
  529.  
  530. --
  531. * Noel Hunter,  Academic Systems Administrator,    Wake Forest University *
  532. * email: noel@wfu.edu         http://www.wfu.edu/users/staff/Noel-Hunter/ *
  533. * tel:910-759-5812 fax:910-759-6074 home:910-725-6570 mobile:910-418-8286 *
  534.